<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
    <title>Setup</title>
    <link rel="stylesheet" type="text/css" href="css/common.css" />
    <link rel="stylesheet" type="text/css" href="css/screen.css" media="screen" />
    <link rel="stylesheet" type="text/css" href="css/_print.css" media="print" />
    <link rel="stylesheet" type="text/css" href="css/prettify.css" media="screen" />
  </head>
  <body onload="prettyPrint(); decorate();">
    <script type="text/javascript">prefix='';	</script>

    <script type="text/javascript" src="templates/header.js"></script>
    <script type="text/javascript" src="js/prettify.js"></script>
    <script type="text/javascript" src="js/jquery-min.js"></script>
    <script type="text/javascript" src="js/decorator.js"></script>
    
    <div id="left">
      <script type="text/javascript" src="templates/left.js"></script>
    </div>
  
    <div id="content">
	
	
    <h2 class="doAnchor">Classpath Setup</h2>

    <p>In order to run the examples provided in the documentation, you
    need to add the following jars to your class path:
    </p>

    <ul>
      <li>logback-core-${project.version}.jar</li>
      <li>logback-classic-${project.version}.jar</li>
      <li>logback-examples-${project.version}.jar</li>
      <li>slf4j-api-${slf4j.version}.jar</li>
    </ul>
    
    <p>The <em>logback-*.jar</em> files are part of the logback
    distribution whereas <em>slf4j-api-${slf4j.version}.jar</em> ships
    with <a href="http://www.slf4j.org">SLF4J</a>, a separate project.
    </p>
    

    <h3 class="doAnchor" name="commandLine">Running from the command
    line</h3>
    
    <p>You can launch the first sample application,
    <em>chapters.introduction.HelloWord1</em> with the following
    command. This assumes that your current directory is
    <em>$LOGBACK_HOME/logback-examples</em>, where
    <em>$LOGBACK_HOME</em> stands for the directory where you
    installed logback:
    </p>

    <p class="source">java -cp lib/slf4j-api-${slf4j.version}.jar;../logback-core-${project.version}.jar;\
 ../logback-classic-${project.version}.jar;logback-examples-${project.version}.jar\
 chapters.introduction.HelloWorld1</p>

   <p>It is more convenient to set the CLASSPATH environment variable
   once and for all before running the examples.
   </p>

   <p>The <em>setClasspath.cmd</em> script located in the
   $LOGBACK_HOME/logback-examples folder will configure the class path
   for the MS Windows platform. For Unix, you can use
   <em>setClasspath.sh</em>.
   </p>

   <p>Please edit the script in order to adapt the <em>LB_HOME</em> variable 
   to match your local environment.</p>
   
   <p>Please be aware that many examples will launch Java classes
   along with configuration files. To access these files by using the
   same commands as written in the documentation, you will need to
   issue the commands from within the
   <em>$LOGBACK_HOME/logback-examples</em> directory.
   </p>

    
   <h2 class="doAnchor" name="mavenBuild">Maven dependency
    declaration</h2>

    <p>To use logback-classic in your Maven project, declare the
    following dependency in your project's <em>pom</em> file.</p>

    <pre class="prettyprint source">&lt;dependency>
  &lt;groupId>ch.qos.logback&lt;/groupId>
  &lt;artifactId>logback-classic&lt;/artifactId>
  &lt;version>${project.version}&lt;/version>
&lt;/dependency></pre>

    <p><span class="label notice">TRANSITIVITY</span> Note that in
    addition to <em>logback-classic.jar</em>, the above declaration
    will automatically pull-in <em>slf4j-api.jar</em> and
    <em>logback-core.jar</em> into your project by virtue of Maven's
    transitivity rules.</p>


   <p>To include logback-access in your Maven project, declare the following
    dependency in your project's <em>pom</em> file.</p>

    <pre class="prettyprint source">&lt;dependency>
  &lt;groupId>ch.qos.logback&lt;/groupId>
  &lt;artifactId>logback-access&lt;/artifactId>
  &lt;version>${project.version}&lt;/version>
&lt;/dependency></pre>

   <h2 class="doAnchor" name="optionalDeps">Optional dependencies</h2>

   <h3 class="doAnchor" name="SMTP"><code>SMTPAppender</code> requires
   JavaMail API</h3>

   <p><code>SMTPAppender</code> related examples require the JavaMail
   API version 1.4 or later. Once you <a
   href="http://java.sun.com/products/javamail/downloads/index.html">download
   JavaMail</a>, you need to place <em>mail.jar</em> on your class
   path.</p>
   
   <p>Here is the corresponding Maven dependency declaration for your
   convenience.</p>



   <pre class="prettyprint source">&lt;!-- The javax.activation:activation:1.1 dependency will be --&gt;
&lt;!-- automatically pulled in by Maven's transitivity rules --&gt;
&lt;dependency>
  &lt;groupId>javax.mail&lt;/groupId>
  &lt;artifactId>mail&lt;/artifactId>
  &lt;version>${javax.mail.version}&lt;/version>
&lt;/dependency></pre>

   <h3 class="doAnchor" name="groovy"><code>GEventEvaluator</code> and
   <em>logback.groovy</em> configuration files require the Groovy
   runtime</h3>
   
   <p><code>GEventEvaluator</code> depends on the Groovy runtime. It
   was tested with Groovy version ${groovy.version}. Similarly, as the
   name indicates <a href="manual/groovy.html">groovy
   configuration</a> files require the groovy runtime to be present on
   your class path.
   </p>
   
   <p>Here is the corresponding Maven dependency declaration for your
   convenience.
   </p>


   <pre class="prettyprint source">&lt;dependency>
  &lt;groupId>org.codehaus.groovy&lt;/groupId>
  &lt;artifactId>groovy-all&lt;/artifactId>
  &lt;version>${groovy.version}&lt;/version>
&lt;/dependency></pre>


   <h3 class="doAnchor" name="janino">Conditional processing and
   <code>JaninoEventEvaluator</code> require the Janino library</h3>
   
   <p><a href="manual/configuration.html#conditional">Conditional
   processing</a> in configuration files requires the <a
   href="http://docs.codehaus.org/display/JANINO/Home"><b>Janino
   library</b></a>. Moreover, the evaluator examples based on
   <code>JaninoEventEvaluator</code> require Janino as well.  Once you
   download Janino, simply place <em>commons-compiler.jar</em> and
   <em>janino.jar</em> on your application's class path.
   </p>

   <p><span class="label notice">Don't forget</span> As of Janino
   version 2.6.0, in addition to <em>janino.jar</em>,
   <em>commons-compiler.jar</em> needs to be on the class path as well.</p>

   <p>Here is the corresponding Maven dependency declaration for your
   convenience.
   </p>

   <pre class="prettyprint source">&lt;!-- The org.codehaus.janino:commons-compiler:${janino.version} dependency --&gt;
&lt;!-- will be automatically pulled in by Maven's transitivity rules --&gt;
&lt;dependency>
  &lt;groupId>org.codehaus.janino&lt;/groupId>
  &lt;artifactId>janino&lt;/artifactId>
  &lt;version>${janino.version}&lt;/version>
&lt;/dependency></pre>


   <h2 class="doAnchor" name="ide">Building Logback with an IDE</h2>

   <p class="big green">As of version 1.3.x, logback requires Java 9
   to build. However, it can be run on Java 8 or later. Logback
   version 1.2.x, requried Java 6.x</p>
   
   <p>If you wish to contribute to the project or just hack for fun,
   you will probably want to import logback as a project into your
   favorite IDE. Logback uses Maven as its build tool. Logback offers
   a Groovy-based configurator so there is a dependency on the Groovy
   language. It follows that your IDE should have plugins for Maven
   and Groovy in order to <em>build</em> logback from your within
   IDE. The Groovy dependency just mentioned is a <em>build-time</em>
   dependency. The only mandatory logback dependency at runrime is the
   JRE, unless of course you wish to use the Groovy configurator in
   which case Groovy runtime will be a required dependency as
   well. Also note that building from the command line is fairly
   trivial, the command 'mvn install' given from $LOGBACK_HOME folder
   should suffice. </p>

   <p><span class="label">ask for help</span> Notwithstanding the
   instructions below, if you have trouble building logback from the
   sources, just ask for help on the logback-dev mailing list.</p>

   <h3 class="doAnchor" name="idea">Building logback with IntelliJ
   IDEA</h3>

   <p>Assuming you have the latest version of IntelliJ IDEA installed,
   no additional plugin installation is necessary. IntelliJ IDEA
   supports Maven as well as Groovy out of the box. You can import
   logback into IDEA by selecting File&rarr; New Project &rarr; Import
   from external model&rarr; Maven, then select $LOGBACK_HOME as the
   Root directory. The import should finish successfully in a few
   seconds.</p>

   <h3 class="doAnchor" name="eclipse">Building with Eclipse and "mvn eclipse:eclipse"</h3>

   <p>Building logback under Eclipse is a little trickier. Here are
   instructions for building logback under Eclipse using the maven
   eclipse:eclipse plugin.
   </p>
   

   <p>The procedure outlines below assumes that M2Eclipse is not
   active.  If you have <code>m2eclipse</code> installed, you can
   disable it by removing the Maven Nature for a given project. In
   later versions of Eclipse, m2eclipse is installed by default. 
   </p>

   <p>And without further ado here are the steps:
   </p>
   

   <ol>
     <li>Ensure that the Groovy plugin for Eclipse is installed.

       <ul>
         <li>
           <p>You first need to determine the update site appropriate
           for your version of Eclipse. The list of available update
           sites is available from <a
           href="https://github.com/groovy/groovy-eclipse/wiki">Groovy
           Eclipse Wiki</a>.
           </p>
         
         </li>
         
         <li>In Eclipse, select Help &rarr; Intall new Software &rarr;
         Work with the update site you chose in the previous step and
         then Select "Groovy-Eclipse Feature". 
         </li>
       </ul>
    </li>



     <li><pre>cd $LOGBACK_HOME</pre>

     where $LOGBACK_HOME stands for the location where you cloned the
     logback project from github </li>


     <li>From the command line, run <code>mvn eclipse:eclipse</code>
     in $LOGBACK_HOME</li>

     <li>In Eclipse, import the logback project: Import&rarr;
     General&rarr; Existing Projects into Workspace, select
     $LOGBACK_HOME folder for the import
     </li>    

     <li>In Eclipse, clean all projects in Eclipse (Project &rarr;
     Clean)
     </li>   

     <li>In Eclipse, select logback-classic project and check that it has 
     "Groovy" nature. If not add it by right clicking on logback-classic project &rarr;
     Groovy &rarr; Convert Groovy to Project.
     </li>   
     
   </ol>


   <p>The above listed procedure has been last tested by the author
   using Eclipse Neon on March 17th, 2017.</p>

   <h3>Building with Eclipse+m2eclipse</h3>
   
   <p>Building with Eclipse and m2eclipse is a bit more complicated
   due to the use of Groovy in logback-classic.
   </p>

   <p>Here are the required steps:</p>
   

   <ol>
     <li>Ensure that the Groovy plugin for Eclipse is installed. See
     above for instructions.</li>

     <li>In Eclipse, import the logback project: Import&rarr;
     Maven&rarr; Existing Maven Projects, select
     $LOGBACK_HOME folder for the import
     </li>

     <li>Install any discovered m2e connections,
     e.g. "maven-bundle-plugin".
     <p>
       <a href="images/setup/discoverM2EConnectors.png">
         <img src="images/setup/discoverM2EConnectors.png" alt="Click to enlarge" height="400"/>
       </a>
     </p>

     <p>You may need to restart Eclipse.</p>.

     </li>

     <li>In Eclipse, select logback-classic project and check that it
     has "Groovy" nature. If not add it by right clicking on
     logback-classic project &rarr; Groovy &rarr; Convert Groovy to
     Project.
     </li>
     
     <li>At this stage Eclipse may complain about
     <code>GafferConfigurator</code> not being resolved. To fix these
     errors, select logback-classic project properties, select "Java
     Build Path" &rarr; Source &rarr; "logback-classic/src/main/groovy".
     Select "Excluded" and then click on Remove.
     
     <p>
       <a href="images/setup/removeGroovyExclusions.png">
         <img src="images/setup/removeGroovyExclusions.png" alt="Click to enlarge" height="400"/>
       </a>
     </p>

     </li>

     <li>
       <p>Project &rarr; Clean &rarr; Clean all projects.</p>     
     </li>

     
     <li>To fix the errors in the logback-examples project, you need
     to instruct logback-classic to not export its Maven dependencies.
     Select logback-classic project properties, select "Java
     Build Path" &rarr; Order and Export and deselect "Maven Dependencies".

     <p>
       <a href="images/setup/deselectMavenDependenciesExport.png">
         <img src="images/setup/deselectMavenDependenciesExport.png" alt="Click to enlarge" height="400"/>
       </a>
     </p>
     </li>

     <li>
       <p>Project &rarr; Clean &rarr; Clean all projects.</p>     
     </li>
     
     

   </ol>
   
   
   
   
   <p><span class="label notice">Call for volunteers</span> Given that
   many users prefer M2Eclipse for building projects under Eclipse
   IDE, we are looking for volunteers to help simplify the steps
   required for building logback with M2Eclipse.
   </p>
   

   <script src="templates/footer.js" type="text/javascript"></script>
</div>
</body>
</html>
